home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 January: Mac OS SDK / Dev.CD Jan 97 SDK2.toast / Development Kits (Disc 2) / OpenDoc Development Framework / ODFDev / ODF / Other View Systems / MacApp Views / MacApp Views.doc < prev   
Encoding:
Text File  |  1996-09-17  |  5.9 KB  |  150 lines  |  [TEXT/MPS ]
  1.                 *********************************************
  2.                 MACPP VIEWS SUPPORT IN ODF 1 • RELEASE NOTES
  3.                 *********************************************
  4.  
  5. These release notes cover the MacApp views support in ODF.  This is a technical
  6. complement to the ReadMe files "Q & A" and "User Guide" which should be read first.
  7. In particular the "User Guide" explains how to add MacApp support to your part
  8. and how to support custom classes.
  9.  
  10. MACAPP READER MODULE
  11. --------------------
  12.  
  13. We call "MacApp Reader" the code contained in the 2 source files FWMARead.cpp and
  14. FWMAObjs.cpp. 
  15.  
  16. FWMARead.cpp implements the static class FW_CMacAppReader whose job is to parse
  17. the View resource stream, and for each view create a temporary object and then
  18. create the converted ODF view.  FWMAObjs.cpp implements the classes for these
  19. temporary objects, with a root class FW_CMAObject.
  20.  
  21. MACAPP WARNING
  22. --------------
  23.  
  24. When loading a MacApp view you may get the following debugger break:
  25.  
  26.    "FW_CMacAppReader::ReadStreamObject: Unknown delimiter in resource stream"
  27.  
  28. which leads to the following error message in ViewTester:
  29.  
  30.    "Error reading MacApp 'View' resource ID xxx: found invalid data or couldn't 
  31.    skip unknown view!
  32.    
  33. In that case the MacApp Reader throws an exception and aborts reading further.
  34. This is due to the fact that it was unable to jump over an unknown view object 
  35. because the object size was invalid in the resource stream. The MacApp team 
  36. is aware of this problem and is addressing it for a future version. In the
  37. mean time you have 2 solutions:
  38.  
  39. 1) make sure that the MacApp resource file was generated by Ad Lib and not directly
  40. by Rez compiling a .r file (if this is the case load it first in Ad Lib and save 
  41. it back).  And Ad Lib file has more chances to contain valid information.
  42.  
  43. 2) See in ViewTester what views were created, the last one created should be the
  44. offending one.  Edit the file in Ad Lib and modify the views until this error
  45. disappears.
  46.  
  47.  
  48. SUPPORTED MACAPP CLASSES
  49. ------------------------
  50.  
  51. The following class conversion occurs when reading a View resource:
  52.  
  53. MacApp class            ODF class
  54. +++++++++++++++++++++++++++++++++++++++++++++
  55. TButton                    FW_CButton
  56. TCheckBox                FW_CButton
  57. TCluster                FW_CGroupBox
  58. TDialogBehavior            (used to set the default & cancel buttons)
  59. TDialogView                (sets frame's bounds & default/cancel buttons)
  60. TEditText                FW_CEditView
  61. TPicture                FW_CPictSView
  62. TPopup                    FW_CPopupMenu
  63. TScroller                FW_CScrollBarScroller
  64. TStaticText                FW_CStaticText
  65. TRadio                    FW_CButton
  66. TTEView                    FW_CEditView
  67. TTextGridView            FW_CListBox
  68. TTextListView            FW_CListBox
  69. TWindow                    (sets frame's bounds & creates grow box)
  70.  
  71. All other classes are not registered in FW_CMacAppReader::RegisterAllMacAppClasses()
  72. and thus will be converted to ODF "unknown" views by default, unless your
  73. part registers them and provides the code to convert them.
  74.  
  75. Note: it is not possible to create pure TView or TControl object.
  76.  
  77. CONVERSION RULES & LIMITATIONS
  78. ------------------------------
  79.  
  80. ODF views are restricted to 16-bit coordinates. When reading coordinates or 
  81. sizes greater than 16-bit the MacApp reader gives a debugger warning:
  82.   "MacAppReader Warning: found a view out of 16 bit space. ODF will adjust its bounds."
  83. It resets large coordinates to 0 and large sizes to 16K.
  84.  
  85. MacApp adorners and behaviors are not supported.  They are ignored except for 
  86. TDialogBehavior which is used to set the default and cancel buttons.
  87.  
  88. MacApp doesn't define any specific tabber object so you must create the 
  89. ViewTabber in your PostCreateViewFromStream method.
  90.  
  91.  
  92. TView classes have the following conversion rules and limitations:
  93. (class fields are named as they appear in the Ad Lib class editors)
  94.  
  95. • TView fields:
  96. Only the view ID and coordinates are used. All other fields are ignored
  97. including the size determiners (ODF views are created with their default
  98. binding flags)
  99. When a TView object is the first view inside a scroller its bounds are changed to
  100. match the scroller's bounds.
  101.  
  102. • TScroller fields:
  103. An ODF frame can use only one scrolling view for its content (the content view).  
  104. The first scrolling view is converted into the content view and additional 
  105. scrollers generate a warning and are ignored by ODF. (However you can handle 
  106. scrolling views as custom views like CScrollEdit in Form.)
  107. The TScroller object itself is converted into an ODF FW_CScrollBarScroller and
  108. 1 or 2 scroll bar views are created.  Scroll units are ignored.
  109.  
  110. • TControl fields:
  111. Fields other then Default Choice and Text Style are ignored.
  112. IMPORTANT: the MacApp default button events are converted FW_kButtonPressedMsg.
  113. Of course you can also use your own message values.
  114.  
  115. • TPopup fields:
  116. The label must be defined in a string list (Label field in AdLib). ODF won't
  117. read the label from the MENU resource itself like MacApp does.
  118.  
  119. • TWindow fields:
  120. The only data converted from an LWindow object is its location and the presence
  121. of a grow box. (A grow box is always created in the bottom right corner of the 
  122. frame and its view id is hard-coded to 'grow'.) The type of window cannot be 
  123. used here because the frame's window already exists when its subviews are created.
  124.  
  125. • TDialogView fields:
  126. Same as TWindow + the default and cancel button ids.  The type of dialog window
  127. must be set by program in NewModalDialog().
  128.  
  129. • LListBox fields:
  130. Horizontal Scrollbar and LDEF ID are not supported.
  131. The "Has Grow Box" flag is translated into "Multiple Selection" for ODF.
  132.  
  133. • TEditText & TTEView fields:
  134. Only the maximum number of characters & text style are used.
  135. Form provides an example for converting TTEView to a custom CScrollEdit class.
  136.  
  137. • TTextGridView & TTextListView fields:
  138. Both classes are mapped to FW_CListBox but ODF supports only 1 column text lists.
  139.  
  140. • TPicture fields:
  141. The image size should remain 0, 0 in order to use the picture size by default.
  142. The PICT resource must be present in the same resource file.
  143.  
  144.  
  145. API REFERENCE
  146. -------------
  147.  
  148. <To be documented later.  Please see the code in Form and ViewTester for now>
  149.  
  150.